Library Installer

This document is for publishers or library administrators who need to understand, manage, customize, and deploy library installations. Topics covered in this document are:

Overview

There are some general concepts you need to understand before using Library Installer:

This section provides an overview to these concepts. For instructions on completing the related tasks, see the remaining sections in this document.

Publisher and Administrator Functionality Overview

The Library Installer command-line utility, LibInst.Console.exe, is mainly for deploying and maintaining your library content in an online environment. The Library Installer GUI, LibInst.Gui, is the only interface to Library Installer that your users typically see. So, as a publisher or library administrator, you need to complete the following tasks.

  1. Use the LibInst.Console.exe file to manage your libraries if you:
  2. Have your own public Internet or intranet web site for library content.
  3. Want to validate your library collections and updates on a staging system before deploying them to your end users.
  4. Need to push your library content out to your end users using a 3rd party solution (such as Marimba, CABC, or ZENworks) rather than have them pull it from an update server or install it from a CD or DVD.
  5. Customize LibInst.Gui for your offline consumers by (1) editing a sample XML file (libinst.core.dll.resources.xml) and (2) editing the LibInst.config file.

Content Consumer and Administrator Functionality Overview

Your customers or end users (those who search and read your publications) are considered content consumers. For your content consumers using NXT Solo or Offline Publisher, or library administrators using Intranet Publisher, the Library Installer is a Windows tray application that provides the ability to download and apply updates in the background using the Internet. Although the technical name of this application is LibInst.Gui, the default name and icon displayed for your users is NXT Library Installer.

The user guide provided for your users (Maintaining Your NXT Libraries) explains the following items:

By right-clicking on the NXT Library Installer icon in the Windows tray, your content consumers can use LibInst.Gui to:

Your consumers must have internet access to get updates. If they do not have constant Internet access, Library Installer will check for updates whenever they do have a connection. As a publisher, you initially set the update check frequency (the default is once a day). Your consumers can modify the frequency to suit their needs. They can also force the application to check immediately for updates at any time.

Managing Installations with Library Installer

Use the Library Installer command-line utility (LibInst.Console.exe) to maintain your library deployments. The LibInst.Console.exe is located in (and executed from) the following directory: [application folder]\bin.

Starting LibInst.Console

To start LibInst.Colsole, run LibInst.Console.exe from a command prompt.

Figure 1 shows a usage summary of the LibInst.Console utility.

Figure 1. Usage Summary for the LibInst.Console utility

LibInst.Console Syntax

When you start the Library Installer utility you must include one of the four commands (install, remove, update, or importlicense) and the required variable (librarypath or licensefile). The utility will give you the usage summary again if you try to run the utility without these required arguments. Following are the required syntax for each of the four installation commands:

The LibInst.Console utility command syntax can be broken down into four parts:

The install Command

Use the install command to install or register your library in your site's NXT Site Definition File (SDF) when mounting content on the NXT Online Server. The SDF controls what users see on your NXT site. So, to provide access to new library content on your NXT site you must specify in the SDF that the content exists. When you run this command, the command records the folder and content collection node information in the SDF.


Note: Under Offline Publisher, Solo, or Intranet Publisher, when you deploy your library to your end users for the first time and they install your library on their machine, LibInst.Console is installed and runs to install that library into the site the installation just created. However, this is completely transparent to your end users.


Running this command will also copy your library files to the librarypath directory if it is different from your library's output directory.


Note: Unlicensed libraries are not supported in a secure installation, such as Intranet Publisher or Offline Publisher.


Figure 2 shows a sample usage summary of the install command and its options.

Figure 2. Usage summary of the install command

Options of the Install Command

Table 1 shows options for the install command of the LibInst.Console utility.

Table 1. Options of the install command

Option Example/Description
librarypath Syntax: libinst.console install c:\...\library_folder
This variable is required. This is the directory where your library files (Library.libinst and content collection files) currently reside, OR, it is the directory for where you want your library files to reside.

If your library files already reside in this directory, you may not need any other options to install your library. If your library files reside in a different directory, you can either copy them into this location yourself before running LibInst.Console, or, use the /sp option and have LibInst.Console copy them for you. This must be an existing directory. LibInst.Console will not create it for you.

The path must be to writable media. During an update, the latest library install file and any updates are copied or downloaded to this location. This path cannot change after you install the library.
/sdf:path Syntax: libinst.console install <librarypath> /sdf:c:\...\your_site.sdf
Use this install option to specify the SDF you want to install your library into. If you do not specify the SDF with this option, the Library Installer utility will install your library into Publish.sdf, located in the [application folder]\bin directory, which is the default SDF set up during NXT 4 install.
/vid:id Syntax: libinst.console install <librarypath> /vid:id_of_view
Use this install option to include your library in a particular view on the target site. If you do not specify this parameter LibInst.Console will include your library content in the 10.1048/enu view. This view was built during the NXT 4 install, which is the default view for the sample site.
/sp:path Syntax: libinst.console install <librarypath> /sp:c:\...\library_files_folder
Use this install option to specify the path to the location of the library files including Library.libinst. If your library install file, content collections (.nxt files), and update (.upd) files do not reside in the same location as the librarypath but reside on an accessible server, the /sp option allows you to identify the location of those files. This path is different than the librarypath. When you use this option, Library Installer copies the library files into the librarypath location at install time.

If your library files reside on a CD or DVD with a valid MediaInfo.pid file, Library Installer will only copy the library install file to the librarypath directory. Library Installer assumes you want the content collection files (.nxt) to stay on the CD. If you do not want your .nxt files to remain on the CD, you must manually copy them into the librarypath directory before running this command.
/pl:path

Syntax: libinst.console install <librarypath> /pl:c:\...\<password_file> .pubpwd
Use this install option to specify the path of an exported password list file in order to deploy password protected content collections to your NXT Online Server. This option is mainly for the publisher who wants to publish to a public site or corporate site without licensing content to end users.


Note: You could use this option with Solo or Intranet Publisher, but we strongly advise against it. If you are deploying your library files to NXT Solo users, we strongly recommend you DON'T use this feature for security reasons, because your passwords will be stored in clear text in the site definition file (.sdf). See the "File Menu" topic and the "Library Manager Files" table in Library Manager for more information on exporting passwords.


/gc Syntax: libinst.console install <librarypath> /gc
Use this install option to get collections or retrieve all library files (library.libinst and NXT files) from an update server site that is listed in the library install file.
/silent Syntax: libinst.console install <librarypath> /silent
Use this option to reduce console output to errors only and suppress progress and status output. When you run LibInst.Console with the /silent option, if no message displays, then the install command executed successfully.

The remove Command

Use the remove command to remove a library from a Site Definition File. You would use this command before doing a fresh install of your library (in a testing environment) on the same site, instead of updating. This command does the exact opposite of the install command. Figure 3 shows a usage summary of the remove command and its options.

Figure 3. Usage summary of the remove command

Options of the Remove Command

Table 2 shows options for the remove command of the LibInst.Console utility.

Table 2. Options of the remove command

Option Example/Description
librarypath

Syntax: libinst.console remove c:\...\library_folder
This variable is required. This is the directory where the library files you want to remove (Library.libinst and content collection files) currently reside. This option alone will only remove the reference to the library from the local SDF file. To delete the library files as well, use the /r option.

/r Syntax: libinst.console remove <librarypath> /r
Use this option to remove the reference to your library from the SDF and to delete the library files (Library.libinst and content collection files). In order to remove these files, they must reside on writable media.
/silent Syntax: libinst.console remove <librarypath> /silent
Use this option to reduce console output to errors only and suppress progress and status output. When you run LibInst.Console with the /silent option, if no message displays, then the remove command executed successfully.

The update Command

Use the update command to update library collections that are deployed on an NXT site.

When you run this command, Library Installer (1) takes each collection it needs to update offline, (2) merges each update file into its parent content collection file, and then (3) puts the collection back online. If there are any new content collections (.nxt files), the update command will also copy the new collections and your library install file to the librarypath directory (if needed) and install the new content collections. Figure 4 shows a sample usage summary of the update command and its options.

Figure 4. Usage summary of the update command

Options of the Update Command

Table 3 shows options for the update command of the LibInst.Console utility.

Table 3. Options of the update command

Option Example/Description
librarypath

Syntax: libinst.console update c:\...\library_folder
This variable is required. This is the directory where you want the update files to reside, or, where they currently reside if you do not have a separate location.
If your update files already reside in this directory, you may not need any other options to update your library. If your update files reside in a different directory, you can either copy them into this location yourself before running LibInst.Console, or, use the /sp option and have LibInst.Console copy them for you. This must be an existing directory. LibInst.Console will not create it for you.
The path must be to writable media. During an update, the latest library install file and any updates are copied or downloaded to this location. This path cannot change after you install the library. This will retrieve any update files and Library.libinst.

/c Syntax: libinst.console update <librarypath> /c
Use this update option to check for updates on the update servers and report the results to the console, but do not download and apply the updates.
/no Syntax: libinst.console update <librarypath> /no
Use this update option to prevent the Library Installer utility from reordering your library content nodes in the SDF. By default, the update operation reorders the library in the SDF if it is different from the order in the library install (Library.libinst) file. Therefore, if you reorder (change the hierarchy of) your library collections in the SDF, directly or with the Content Network Manager, then you can use this option to prevent an update from changing your site structure. This update option also retrieves any update files and Library.libinst.
/sp:path Syntax: libinst.console update <librarypath> /sp:c:\...\update_files_folder
Use this update option to specify the path to the location of the update files, if different than the library path. If you do not use this option to get your updates into your library path directory, you must use the /d option. All source update files and the library install file are copied to the specified library path at update time. This update option also retrieves any update files and Library.libinst.
/d Syntax: libinst.console update <librarypath> /d
Use this update option to attempt to download an update from update servers listed in the library install file. This is an alternative to the /sp option. Library Installer will attempt to download updates from each update server in the order you list them in the Update Servers property of Library Manager until all updates have been successfully downloaded. This update option also retrieves any update files and the Library.libinst file.
/gc Syntax: libinst.console update <librarypath> /gc
Use this update option to get collections or retrieve all new content collections that have been added or rebuilt (as opposed to simply updated) to an existing library. This update option is similar to its install option counterpart, in that it retrieves (1) any update files and (2) the Library.libinst file along with the new content collections.
/silent Syntax: libinst.console update <librarypath> /silent
Use this option to reduce console output to errors only and suppress progress and status output. When you run LibInst.Console with the /silent option, if no message displays, then the update command executed successfully.

The importlicense Command

In normal circumstances you will not need to run this command from the console, nor will your end users. This command is invoked when your end user double-clicks on a license file that you have sent him or that they have obtained from your license generation web site. The importlicense command essentially installs the license on their system and allows them to access your library content according to the license's respective subscription. Figure 5 shows a sample usage summary of the importlicense command and its options.

Figure 5. Usage summary of the importlicense command

Options of the importlicense Command

Table 4 shows options for the importlicense command of the LibInst.Console utility.

Table 4. Options of the update command

Option Example/Description
licensefile Syntax: libinst.console importlicense c:\...\license_file.publc
This variable is required. This is the name and location of the license (the .publc file) you want to import or install.
/silent Syntax: libinst.console importlicense <licensefile> /silent
Use this option to reduce console output to errors only and suppress progress and status output. When you run LibInst.Console with the /silent option, if no message displays, then the importlicense command executed successfully.

Customizing the Library Installer GUI

Your content consumers (customers or end users) will not explicitly use the command line version of Library Installer (LibInst.Console). When they install your library for the first time, and when they obtain and install updates from your update servers, LibInst.Console runs in the background. However, this is transparent to your users. Updates to their installed libraries are handled through the Library Installer GUI, which runs in the Windows system tray.

You may want to customize LibInst.Gui to meet your customer needs. The recommended method for customizing this interface is to customize a sample file provided (libinst.core.dll.resources.xml) and add it to the bin folder. The sample file is provided in the Sample Customization folder with the Solo, Offline Publisher, and Intranet Publisher installs.


Note: Some publishers or library administrators may prefer to use the standard .NET Satellite Assembly resource override mechanism for customizations. That may be possible for most LibInst.Gui customizations (with the exception of locking portions of the user interface). However, satellite assemblies have not been tested with LibInst.Gui.


To help you configure and customize the Library Installer user interface, see the following topics:

For information about other installation branding and customization (those not related to LibInst.Gui), see Customizing Icons and Shortcuts and Configuring Install Options.

Setting Default Values

You can set the default values for the Library Installer Update window. This allows you to specify the download options (automatic or prompted) and the frequency that the Library Installer checks for updates. To set the default values, complete the following:

  1. Open the Sample Customization folder. This folder is a sub-folder to the Solo Installation, Offline Publisher Installation, or Intranet Publisher Installation directory, depending on the product you have installed.
  2. Edit the file libinst.config and change the default settings.
  3. Copy the edited file to your Copy folder in your customized installation.
  4. Reference the edited file in the CopyFile.ini file.
  5. Run the install to test the functionality.

Branding LibInst.Gui

When LibInst.Gui starts and is running, your users will see this icon in the Windows tray:  tray icon.

To help your users find the LibInst.Gui for your product, you should change the icon that displays in both the Windows tray and in the upper-left corner of the application windows. You can also edit the icon name displayed. To brand this icon and related text and bubble help, complete the following:

  1. Open the Sample Customization folder. This folder is a sub-folder to the Solo Installation, Offline Publisher Installation, or Intranet Publisher Installation directory, depending on the product you have installed.
  2. Edit the file libinst.core.dll.resources.xml and change the icon settings.
  3. Copy the edited file to your Copy folder in your customized installation.
  4. Reference the edited file in the CopyFile.ini file.
  5. Run the install to test the functionality.

Note: If your users install library content from multiple publishers, they will have multiple tray icons. Although these look like duplicates of the original, they are not. Each tray icon corresponds to an individual library installation, and updates for these are independent from one another. To identify which icon belongs to which publisher, users can right-click on an icon and choose Show Status or Settings from the menu.


Changing Displayed Strings

You can change the text strings in that display in the task bar. To edit these strings, complete the following:

  1. Open the Sample Customization folder. This folder is a sub-folder to the Solo Installation, Offline Publisher Installation, or Intranet Publisher Installation directory, depending on the product you have installed.
  2. Edit the file libinst.core.dll.resources.xml and change the balloon message settings.
  3. Copy the edited file to your Copy folder in your customized installation.
  4. Reference the edited file in the CopyFile.ini file.
  5. Run the install to test the functionality.

Locking Portions of LibInst.Gui

You can lock portions of the LibInst.Gui utility. To lock portions of the LibInst.Gui, complete the following:

  1. Open the Sample Customization folder. This folder is a sub-folder to the Solo Installation, Offline Publisher Installation, or Intranet Publisher Installation directory, depending on the product you have installed.
  2. Edit the file libinst.core.dll.resources.xml and <lock> settings.
  3. Copy the edited file to your Copy folder in your customized installation.
  4. Reference the edited file in the CopyFile.ini file.
  5. Run the install to test the functionality.

To set the default values for these lockable options, you must modify the LibInst.config file. Refer to the sample libinst.config that is provided in redistributable installs (NXT Solo, Intranet Publisher, and Offline Publisher installs).


Note: While it may be possible to use the standard .NET Satellite Assembly resource override mechanism for most LibInst.Gui customization (even thought satellite assemblies have not been tested with LibInst.Gui), locking portions of the user interface is not supported by satellite assemblies due to the unique design of this feature.


Distributing LibInst.Gui Customizations to Your Users

To distribute your customizations to your users, copy the customizations to the user's machine as outlined in Copy Files on Install.

Maintaining Your NXT Libraries

This guide is intended for the user who has one or more of NXT libraries installed. A quick way to determine if you have an NXT library installed is to check your Windows tray (bottom-right of the screen). For every NXT library publisher product installed on your machine (which may contain one or more libraries), you should have one NXT Library Installer icon  tray icon  display in the Windows tray. (Therefore, if you have three publisher products, you should have three icons.)

Library updates are set up on your machine to automatically update once a day (as long as you have an internet connection). You can mostly ignore the NXT Library Installer icon. However, you may choose to use this application at any time if you want to force an immediate update. The following topics related to library maintenance are covered in this user guide.


Note: The remaining content in this document, has been prepared for your content consumers (customers or end users). You may use this section of the document as a user guide for your users. Feel free to copy and modify this content as needed before redistributing to your users or to use this content yourself to test the user experience with the LibInst.Gui.


Start the Library Installer GUI

If you are an online user, you do not need to start the Library Installer GUI or log in (unless instructed to do so by your publisher or library admininstrator).

If you are NXT Solo or Offline Publisher user, the NXT Solo and Offline Publisher installations configure Library Installer GUI to start automatically when Windows starts. However, if Library Installer GUI does not start automatically, you can start it from the Start menu or the command line.

From the Start menu, choose Start > Programs > Rocket > NXT 4 > Online Server > Library Installer (or the path specified by your library publisher or administrator).

From the command line:

If you are an NXT Solo user or Offline Publisher user, the first time you start a Library Installer GUI, you may need to log in to the update server. If this is necessary, the Library Installer will display a login window.

  1. In the login window, enter all required information (username, password, and possibly domain if required by your publisher).
  2. Click OK to continue or Cancel to close the window. If you choose to cancel, however, you will not receive downloads and you will be prompted to enter the information again the next time.

Note: Your domain may be different for each update server you use. For example, if you travel you may choose to use a local update server in a different domain than your regular update server. In these cases, you will be prompted to provide the login information for the alternate server.


Use the Library Installer GUI

Use the Library Installer GUI to maintain your installed libraries.


Note: LibInst.Gui does not start unless there is at least one library installed. If you do not have an installed library on your site, an error window appears informing you of such, and LibInst.Gui does not start. Contact your publisher if this happens.


View the Menu

To view your library maintenance options, right-click on the Library Installer GUI icon tray icon.

Show Status

To check the status of update downloads and installs, right-click on the Library Installer GUI icon tray icon and choose Show Status. The following window is displayed.

Figure 6. Show Status window of Library Installer

This window provides you with information regarding your scheduled updates as well as unscheduled updates.

If you receive an error message that the update server was not found or that the update failed, check the internet connection or contact the content publisher to determine if the update URL server has changed. Click the Save button if you want to save the status report to a text file. Click the Close button to close the status window. The Cancel Update button is only available while Library Installer is downloading and installing an update. Click this button during this time to terminate an update.

Check for Update

To immediately check for new updates (even when a check is not scheduled), right-click on the Library Installer GUI icon tray icon and choose Check for Update. The notification window for the tray icon changes to Checking for update..., and you can view the status window (choose Show Status from the tray icon menu) to check progress.

Downloading happens in the background when you are connected to the Internet (or your Intranet). Detection of an Internet connection is automatic. However, if you cancel a download, or disconnect before the update files are completely downloaded, the Library Installer retains a temporary copy of the data that has been downloaded to this point. Then, when it next checks for updates and detects that it still has to download the previously cancelled update file, it will resume the download from the point of interruption rather than from the beginning of the file.

This feature has been added to ensure that in situations where downloading a whole update file takes too long or cannot complete due to the reliability of the connection, it can still be retrieved over the course of a number of download attempts. When a download is resumed, the progress bar on the status window will start at the point that the last download ended. For example, if the download was interrupted after 60% of the file had been downloaded, the progress bar will start at 60% when the download is next resumed.

There are two scenarios when the resumable download feature will request again the whole file rather than resuming a previous download. The first of these occurs when the download of the interrupted file has not been running for a minimum of 5 minutes. Due to the fact that the initial download request requests the file in compressed form (and resumed downloads do not), this is an optimization to ensure that, in this situation, the whole (compressed) file is requested rather than resuming the download of most of the file in uncompressed form. The second scenario occurs if the update file is changed in any way on the server. If the Library Installer detects that the update file has changed since the last partial download, it will request again the whole file in order to ensure its integrity.

Settings

The Settings window shows the libraries that are installed from a particular publisher, the publisher information for the library, and the updates servers used by that library. It also provides update options so you may control the frequency of your updates.

To display the Settings window with the Library tab selected, right-click on the Library Installer GUI icon tray icon, and select Settings.

Figure 7. Library Installer Settings - Library Tab

Use the Library tab to select a library and configure its settings. Table 5 shows a list of fields of the Library tab.

Field Library Tab Field Description
Select Library A drop down list contains installed libraries so you can select the one for which you want to change settings.
Publisher A read-only string that contains the name of the library's publisher.
Web Site A link to the library publisher's web site in case you need additional information.
Update Servers A drop down list of mirror servers you can use for updates. You can choose a default update server that is closest to your location. If that server is not available, then Library Installer will try the other update servers in the list. The Update URL is a read-only string that shows the URL for the selected mirror site.

Click on the Update tab to see the properties in the following figure.

Figure 8. Library Installer Settings - Update Tab

Use the Update tab to set update preferences and to schedule updates.

Field Update Tab Field Description
Automatically download and apply any update No user interaction is required. The download and update operation is completely automatic. This behaviour is consistent on scheduled updates as well as unscheduled updates.
Notify me before downloading any updates Requires user interaction. If the Library Installer detects new updates on the update server, it displays a window that informs you that updates are present, and ask if you want to proceed with the download and installation of those updates. Once you confirm you want to download and install the updates, Library Installer proceeds with downloading and installing the updates as usual.
Automatically download and apply updates after random delay period No user interaction is required. The download and update operation is completely automatic. The difference between this option and the first is that the Library Installer will not check for an update as soon as a network connection is detected. Instead, it will wait a random amount of time before checking for an update (between 0 and the number of hours specified in the Maximum number of hours for random delay period setting). This helps prevent network traffic bottlenecks when everyone comes into the office at 9:00 am and tries to download their updates.
Check for Update Every Settings are used to specify the interval to check for updates. LibInst.Gui always checks for updates when it first loads. If your computer is constantly on, use this box to specify the interval to check for updates. The starting time point for intervals is the time the application first starts or the last time you changed the interval setting. If you want to check for updates immediately after changing the update settings (or at any other time), right-click on the tray icon and choose Check for Update.

Recommended update intervals depend on the publishers who provide content. Some libraries are only updated quarterly or annually, but others might update content daily or weekly. Publishers may set a default check for update interval by shipping the LibInst.config file with an install, but you can modify this through this window. Since there is little overhead involved in checking for updates, so you can select whatever interval you need to ensure you always stay current.

Maximum number of hours for random delay period Sets the maximum delay the Library Installer may use before checking for updates. This option is only used when the Automatically download and apply update after random delay period option is selected. Enter the maximum amount of time, in hours, that the Library Installer may wait before checking for an update after the system connects to the network. (Valid values are 1-24, inclusive.) The Library Installer then generates a random number of minutes that it waits before performing its first check for updates. Subsequent update checks follow the values in Check for Update Every settings (assuming the system is continuously connected to the network).

About

To view version information about Library Installer GUI (LibInst.Gui), right-click on the tray icon and select About.

Exit

To close the Library Installer GUI (which removes the tray icon and stops checking for library updates), right-click on the tray icon and select Exit.

Viewing a List of Your Installed Licenses

If you are an Offline Publisher or Intranet Publisher user (both license-managed installations), you may find it helpful to view a list of your currently installed licenses for a particular product. The licenses control access to content, as well as the expiration dates for the content. By reviewing these periodically, you can make decisions on when to upgrade or renew your subscriptions to the publisher content.


Note: Unlicensed libraries are not supported in a secure installation, such as Intranet Publisher or Offline Publisher.


To view your custom list of installed licenses, start the publisher's application (usually from the icon on the desktop or from the Start menu) so you can see the content. You must then modify the URL shown in the browser. Delete everything after http://localhost/nxt/gateway.dll? and add in f=license&license_xsl=lbr-all-licenses.xsl. For example, your URL may look like the following (the port number may be different or non-existent): http://localhost:2242/nxt/gateway.dll?f=license&license_xsl=lbr-all-licenses.xsl

Summary

The Library Installer is both a publisher utility and a content-consumer Windows tray application. It helps to ensure that your clients get the most current information available. As a publisher, you use the Library Installer command-line utility to install, update, and remove your libraries in and from your NXT site or CD/DVD publications and import licenses for libraries on your site. As content consumers, your customers use the Library Installer Windows tray application to check for, retrieve, and install your library updates. Library Installer used in conjunction with Library Manager provides you with an end-to-end publishing solution with automatic content capabilities for you and your clients.